\documentclass[american]{rtxarticle}

\usepackage{listings}
\usepackage{tikz}
\usetikzlibrary{shapes,fit}

\lstset{%
basicstyle=\ttfamily\footnotesize\color{LightGray},
backgroundcolor=\color{black}
}

\tikzset{warrow/.style={->, >=stealth, color=black, ultra thick}}

\tikzset{graybox/.style={draw,rectangle,rounded corners=3pt,very thick,densely dashed,color=gray!75,text=black}}
\tikzset{redbox/.style={draw,rectangle,rounded corners=5pt,ultra thick,color=rathaxesred,text=white}}
\tikzset{redcontainer/.style={draw,rectangle,rounded corners=5pt,ultra thick,color=rathaxesred,text=white,minimum height=2.5cm,minimum width=6cm}}

\title{First steps}
\author{Louis Opter}

\rtxdoctype{User Documentation}
\rtxdocstatus{Release}
\rtxdocversion{0.5}

\rtxdochistory
{
0.1 & 04/07/2011 & Louis Opter & Initial release \\
\hline
0.2 & 04/09/2011 & Louis Opter & Lot of improvements \\
\hline
0.3 & 04/09/2011 & David Pineau & Quick fixes \\
\hline
0.4 & 07/19/2011 & Louis Opter & Add on overview of the generation of a driver \\
\hline
0.5 & 01/08/2012 & Louis Opter & Update to cover the latest improvements \\
}

\begin{document}

\maketitle

\begin{abstract}
\rtx\ is a Domain Specific Language to describe peripherals drivers. It
compiles to kernel modules written in C for any defined Operating System.

This document explains how to setup the \rtx\ compiler on Windows and Unix like
platforms and generate your first peripheral driver.

This document will also give you links to the complete documentation and
explains how to build the latest version of \rtx.
\end{abstract}

\tableofcontents

\pagebreak

\section{Installation}

An installer exists for Windows, on other operating systems only installations
from the sources are supported at the moment. Of course, if you intend to
develop on \rtx\ itself from Windows you can also choose to install \rtx\ from
the sources (i.e: without the installer).

\subsection{Pre-requisites}

\rtx\ doesn't need to be installed on the same operating system as the
operating system you target to generate drivers. In other words, you can
install \rtx\ on Windows and generate the sources of a Linux driver (that is,
from Windows).

We made it very easy to build \rtx\ source files from a CMake ``Makefile'', so
you will need to install \href{http://www.cmake.org/}{CMake} (>= 2.6) along with
\rtx\ to build our first example. CMake works on all the operating systems
supported by \rtx\ and has a \href{http://www.cmake.org/cmake/resources/software.html}{Windows
installer}\footnote{When you install CMake on Windows, make sure to select the
option to add CMake to the system \texttt{PATH} for all users.}.

CMake uses the native build tools for your operating system, that means that you
will need to install ``make'' on an Unix-like (this often shipped in a
``\texttt{build-essential}'' package). And, that you will need to install the
\href{http://www.microsoft.com/download/en/details.aspx?id=8279}{Windows SDK} on
Windows.

Finally, if you intend to build the source generated by \rtx\ you will also need
the Linux sources on Linux, the Microsoft Windows Driver Development Kit on
Windows and so on.

\subsection{Using the Windows installer}

An installer is available for Windows. It includes everything you need to write
drivers using \rtx: the \rtx\ compiler and its documentation.

Download the \href{http://rathaxes.googlecode.com/files/rathaxes-latest.exe}{installer},
then simply execute it and follow the on-screen instructions.

\subsection{From the sources on Unix}

If you are not on Windows you will have to install \rtx\ from a ``source
release''.

You will need to have CMake >= 2.6 installed and to download a
\href{http://rathaxes.googlecode.com/files/rathaxes-src-latest.tar.gz}{\rtx\ source tarball}.

Then extract the source tarball and ``cd'' into it, finally you can install
\rtx\ using:

\begin{lstlisting}
$ mkdir build
$ cd build
$ cmake -DCMAKE_INSTALL_PREFIX=/usr/local/ -DCMAKE_BUILD_TYPE=RELEASE ..
$ sudo make install
\end{lstlisting}

\emph{You will need to be root to issue ``make install'', this example uses
``sudo'' but you may need to adapt it to your local setup.}

\section{Generate your first driver}

The process to generate a driver is roughly the same but some tools and paths
are a bit different, so pick the instructions for your Operating System.

\subsection{From Windows}

Open the ``\rtx\ Shell''. Then, ``cd'' somewhere you have read-write rights and
generate the sources of our ``LKM'' example:

\begin{lstlisting}
$ mkdir build
$ cd build
$ cmake "-GNMake Makefiles" %RATHAXES_PATH%/share/doc/samples/LKM/
$ nmake lkm_src
\end{lstlisting}

\subsection{From any Unix like}

Open your favorite terminal emulator and generate the sources of our ``LKM''
example:

\begin{lstlisting}
$ mkdir build
$ cd build
$ cmake /usr/share/doc/rathaxes/samples/LKM/
$ make lkm_src
\end{lstlisting}

If you are on Linux and have a valid source tree you can also compile the kernel
module you just generated:

\begin{lstlisting}
$ make lkm
\end{lstlisting}

\section{Diving in}

Before we explain the compiler and the language in details, here is an overview
of the generation of a driver:

\begin{figure}[ht!]
\begin{center}
\begin{tikzpicture}
\node (RTX) at (-5,0) {\includegraphics[height=1.5cm]{icons/rtx_no_stroke}};
\draw (RTX.south) node[below]{\large{\sffamily{Driver description}}};

\node (C) at (5,0) {\includegraphics[height=1.5cm]{icons/c_no_stroke}};
\draw (C.south) node [below]{\large{\sffamily{Kernel module}}};

\node[graybox] (AST1) at (-2,0){\texttt{\large{AST}}};
\draw[warrow] (RTX)--(AST1);

\node[graybox] (AST2) at (2,0) {\texttt{\large{AST}}};
\draw[warrow] (AST2)--(C);

\node[redcontainer] (COMPILER) at (0,0) {};
\draw (COMPILER.south) node[below]{\large{\sffamily{Compiler}}};

\node[graybox] (RTXLINK) at (COMPILER.center) {\texttt{\large{RTX\_Link}}};
\draw[warrow] (AST1)--(RTXLINK);
\draw[warrow] (RTXLINK)--(AST2);

\node (RTI) at (-1.5,2.7) {\includegraphics[height=1.3cm]{icons/rti_no_stroke}};
% The hidden character is a hack to verticaly align "Code templates" and "Interfaces"
\draw (RTI.north west) node[above right]{\large{\sffamily{Interfaces\textcolor{white}{p}}}};
\draw[warrow] (RTI.south)--(RTXLINK);

\node (BLT) at (0.5,2.7) {\includegraphics[height=1.3cm]{icons/blt_no_stroke}};
\draw (BLT.north west) node[above right]{\large{\sffamily{Code templates}}};
\draw[warrow] (BLT.south)--(RTXLINK);
\end{tikzpicture}
\caption{Overview of the generation of a driver}
\end{center}
\end{figure}

You can see that the compiler uses three types of files. These files all have
different extensions but are actually written in the same language: \rtx. (Like
in C, where \texttt{.c} and \texttt{.h} files have different extensions but are
written using the same language). These three ``kind'' of files have different
purposes:
\begin{description}
\item [{\texttt .rtx}] : describes your driver as well as its specific and
platform-independent algorithms;
\item [{\texttt .rti}] : hold \emph{interfaces} that describe what must be
implemented in the \texttt{.rtx} file and what will be provided by the
\emph{templates} described in the \texttt{.blt} files;
\item [{\texttt .blt}] : hold \emph{chunks} of C instrumented code that can be
OS specific, the chunks are specified using informations written in the
\texttt{.rtx} file and system introspection.
\end{description}

A \rtx\ project is compiled of one \texttt{.rtx} file and one or several
\texttt{.rti} and \texttt{.blt} files. The complete documentation of the part of
the language used to write \texttt{.rtx} files is available here:
\href{http://rathaxes.googlecode.com/files/dsl_frontend_en.pdf}{dsl\_frontend\_en.pdf}.
Another document covers the \texttt{.rti} and \texttt{.blt} files:
\href{http://rathaxes.googlecode.com/files/dsl_backend_en.pdf}{dsl\_backend\_en.pdf}.

\section{Install the development version}

You can install the latest version of \rtx\ if you need to have the latest bugs
and features or if you want to contribute to the project. This involves checking
out the current version of the project using Mercurial and to build it manually.

\subsection{Pre-requisites}

To checkout and build the project you need to install the following softwares:
\begin{itemize}
\item Mercurial >= 1.5 (you can check the version with ``hg {-}{-}version'' and
      use \href{http://tortoisehg.bitbucket.org/download/index.html}{TortoiseHg}
      on Windows);
\item Subversion (you need to install \href{http://www.sliksvn.com/en/download}{Slik
      SVN} on Windows which ships the command line executables).
\end{itemize}

As well as the requirements to use \rtx\ (CMake and a compiler tool-chain). If
you want to generate the documentation you will also need a \LaTeX\ distribution
(\href{http://www.tug.org/texlive/}{\TeX Live} >= 2009 or \href{http://www.miktex.org/}{Mik\TeX}
on Windows) and \href{http://pages.cs.wisc.edu/~ghost/}{Ghostscript}.

\subsection{Checkout the sources}

Open a shell (from the Visual Studio menu on Windows), and checkout the project
using:

\begin{lstlisting}
$ hg clone https://rathaxes.googlecode.com/hg/ rathaxes
$ cd rathaxes
\end{lstlisting}

Keep the shell open, the next section explains how to build \rtx\ on Windows or
Unix.

\subsection{Build \rtx}

If you are using an Unix like operating system use the following commands:

\begin{lstlisting}
$ mkdir build
$ cd build
$ cmake ..
$ make
\end{lstlisting}

If you are on Windows use:

\begin{lstlisting}
$ mkdir build
$ cd build
$ cmake "-GNMake Makefiles" ..
$ nmake
\end{lstlisting}

\rtxmaketitleblock

\end{document}
